[WIP] Migrate command #7693

zth · 2025-07-21T19:34:46Z

Tracks deprecated usages in the cmt
Uses that info to produce/apply migrations to a single file, according to a user-defined template

Instructions for adding more migrations to the stdlib

Add new @deprecated with a migration prop to anything in the stdlib
Run make lib so it's built into the stdlib files

In tests/tools_tests:

Run yarn rescript legacy clean to ensure you get the new changes
Add sample usages to a StdlibMigration_ModuleName.res file
IF NEEDED (as in if the migration will not be able to compile after being done, because of type mismatches that cannot be fixed automatically or similar), add your sample usage to a StdlibMigrationNoCompile_ModuleName.res file instead. This will not get compiled for testing (but it will get migrated)
Run make (still inside of tests/tools_tests) to run run the migrations and builds. This should get your test output

Repeat the process above until done.

TODO

Add errors on invalid structure of the @deprecated attribute
Error if the wrong type of migration template is provided (ident for function, etc)
Do deep replace of argument mapping, so nested things like someThing(~someArg=[Some(%insert.unlabelledArg(1))]) works
Explore supporting mapping unlabelled arg 0 (using the _ mechanism)
Explore type checking the templates
Explore how tests for migrations can easily be written

pkg-pr-new · 2025-07-22T22:00:57Z

Open in StackBlitz

rescript

npm i https://pkg.pr.new/rescript-lang/rescript@7693

@rescript/darwin-arm64

npm i https://pkg.pr.new/rescript-lang/rescript/@rescript/darwin-arm64@7693

@rescript/darwin-x64

npm i https://pkg.pr.new/rescript-lang/rescript/@rescript/darwin-x64@7693

@rescript/linux-arm64

npm i https://pkg.pr.new/rescript-lang/rescript/@rescript/linux-arm64@7693

@rescript/linux-x64

npm i https://pkg.pr.new/rescript-lang/rescript/@rescript/linux-x64@7693

@rescript/win32-x64

npm i https://pkg.pr.new/rescript-lang/rescript/@rescript/win32-x64@7693

commit: cbb9407

Copilot

Pull Request Overview

This PR implements a new migrate command for ReScript that tracks deprecated usage in compiled TypeScript (.cmt) files and applies user-defined migration templates to automatically update code. The implementation includes comprehensive stdlib migrations for transitioning from Js.Array2.* functions to modern Array.* equivalents.

Adds a complete migration framework with AST transformation capabilities for function calls, pipes, and references
Integrates deprecated usage tracking into the compiler's type checking and CMT generation pipeline
Provides extensive test coverage with stdlib array function migrations and validation of both compilable and non-compilable migration scenarios

Reviewed Changes

Copilot reviewed 37 out of 38 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
tools/src/tools.ml	Core migration command implementation with AST mapper and template application logic
tests/tools_tests/test.sh	Test framework integration for migration command testing
tests/tools_tests/src/migrate/*	Test files demonstrating various migration scenarios and expected outputs
runtime/Js_array2.res	Adds @deprecated annotations with migration templates for all Js.Array2 functions
compiler/ml/*	Compiler integration for tracking deprecated usage in CMT files
runtime/Stdlib_Array.resi	Documentation additions for Array copyWithin functions

Comments suppressed due to low confidence (3)

tools/src/tools.ml:1316

[nitpick] The variable name labelled_args_that_will_be_mapped is verbose and could be shortened to mapped_labelled_args or labelled_to_map for better readability.

      let labelled_args_that_will_be_mapped = ref [] in

tools/src/tools.ml:1317

[nitpick] The variable name unlabelled_positions_that_will_be_mapped is excessively long and could be shortened to mapped_positions or positions_to_map.

      let unlabelled_positions_that_will_be_mapped = ref [] in

tests/tools_tests/src/migrate/StdlibMigration_Array.res:150

The test demonstrates parameter reordering in reduce functions but lacks verification that the migration correctly handles the parameter position changes from (fn, initial) to (initial, fn).

let reduce1 = [1, 2, 3]->Js.Array2.reduce((acc, x) => acc + x, 0)

Copilot · 2025-07-23T08:13:10Z

tools/src/tools.ml

+        expr =
+          (fun mapper exp ->
+            match exp with
+            | {pexp_desc = Pexp_ident {loc}}


The pattern matching for pexp_desc = Pexp_ident {loc} could be more specific by including the identifier in the pattern to make the intent clearer and avoid potential issues if the location check fails.

Suggested change

| {pexp_desc = Pexp_ident {loc}}

| {pexp_desc = Pexp_ident {loc; txt}}

Copilot · 2025-07-23T08:13:11Z

tools/src/tools.ml

+                      };
+                }
+              | _ ->
+                (* TODO: More elaborate warnings etc *)


The TODO comment lacks specificity about what kind of warnings should be implemented. Consider adding more detail about the expected behavior when migration templates are invalid.

Suggested change

(* TODO: More elaborate warnings etc *)

(* TODO: Implement detailed warnings for invalid migration templates.

Consider logging a warning with the location and details of the invalid template.

Decide whether to fallback to a default behavior or propagate the error. *)

Copilot · 2025-07-23T08:13:11Z

tools/src/tools.ml

+                (* TODO: More elaborate warnings etc *)
+                (* Invalid config. *)


Duplicate TODO comment - consider consolidating error handling logic into a shared function rather than repeating the same TODO in multiple places.

Suggested change

(* TODO: More elaborate warnings etc *)

(* Invalid config. *)

handle_warning "Invalid configuration encountered during transformation.";

Copilot · 2025-07-23T08:13:11Z

tools/src/tools.ml

+                (* TODO: More elaborate warnings etc *)
+                (* Invalid config. *)


Third occurrence of the same TODO comment. This indicates a need for a centralized error handling approach for invalid migration configurations.

Suggested change

(* TODO: More elaborate warnings etc *)

(* Invalid config. *)

handle_invalid_migration_config ~context:"Invalid migration template in deprecated function call";

Copilot · 2025-07-23T08:13:11Z

compiler/ml/builtin_attributes.ml

+    (* TODO: Validate and error if expected shape mismatches *)
+    match reason with
+    | Some reason -> Some (reason, migration_template)


Missing validation of migration template structure could lead to runtime errors or incorrect migrations. Input validation should be implemented to ensure the migration template has the expected format.

Suggested change

(* TODO: Validate and error if expected shape mismatches *)

match reason with

| Some reason -> Some (reason, migration_template)

let validate_migration_template template =

match template.pexp_desc with

| Pexp_constant (Pconst_string (_, _)) -> Some template

| _ -> None

in

let validated_template = Option.bind migration_template validate_migration_template in

match reason with

| Some reason -> Some (reason, validated_template)

tools/src/tools.ml

Co-authored-by: Médi-Rémi Hashim <[email protected]>

zth marked this pull request as draft July 21, 2025 19:34

zth force-pushed the tools-migrate branch from b485278 to a3d443f Compare July 22, 2025 16:55

cristianoc requested a review from Copilot July 23, 2025 08:11

Copilot AI reviewed Jul 23, 2025

View reviewed changes

cknitt mentioned this pull request Jun 12, 2025

Consolidate Stdlib APIs before v12 release #7127

Open

5 tasks

mediremi mentioned this pull request Jul 24, 2025

WIP: V12 migration guide rescript-lang/rescript-lang.org#1048

Open

mediremi reviewed Jul 24, 2025

View reviewed changes

tools/src/tools.ml Outdated Show resolved Hide resolved

zth and others added 22 commits July 24, 2025 18:57

wip migrate command

baa9204

fix

b2b9736

remove comment

7d5e022

propagate context info for deprecated, and handle pipe without arguments

f8f80af

comment

9bc687d

comment

583cfd8

add + adapt to a few stdlib migrations

cfeaf9a

handle mapping labelled arg to unlabelled

e5e85ba

support unlabelled arguments as well

ef5e9fd

format code

491f835

format

5d905e8

update snapshots

b1a0418

update analysis tests

4d7759d

support value references

1877e63

do not use unavailable fn

8fe1e62

format

f141424

do not use unavailable fn

eacdb19

Update tools/src/tools.ml

8eb4451

Co-authored-by: Médi-Rémi Hashim <[email protected]>

Add Int.Bitwise.land migration

e257228

Add missing brackets to migration

8c83944

Add migrations for remaining Int.Bitwise functions

a93cac9

Remove newline in toPrecisionWithPrecision doc comment

ee59e26

mediremi and others added 11 commits July 24, 2025 18:57

Add CHANGELOG entry

4ae43d4

Update StdlibMigration_Int expectation

46838c7

emit clarifying comment in migrated files

379b1f9

commit new output

4de7098

formatting

b388259

avoid some warnings

82d84a0

update test output

1749047

migrations for Js_string2

72e5314

add chained to show weirdness

e56c943

format and testoutput

2d60a7b

changelog

0081583

zth force-pushed the tools-migrate branch from 9818a10 to 0081583 Compare July 24, 2025 16:57

zth added 5 commits July 24, 2025 19:09

update

4ddcfac

Js.log -> Console.log

678651a

deprecate Js_console

a3be4a3

format

f581ce9

fix tests

3c43dd4

zth mentioned this pull request Jul 24, 2025

Deprecation/removal of obsolete features #6999

Open

7 tasks

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

[WIP] Migrate command #7693

[WIP] Migrate command #7693

Uh oh!

zth commented Jul 21, 2025 •

edited

Loading

Uh oh!

pkg-pr-new bot commented Jul 22, 2025 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI Jul 23, 2025

Uh oh!

Copilot AI Jul 23, 2025

Uh oh!

Copilot AI Jul 23, 2025

Uh oh!

Copilot AI Jul 23, 2025

Uh oh!

Copilot AI Jul 23, 2025

Uh oh!

Uh oh!

Uh oh!

	\| {pexp_desc = Pexp_ident {loc}}
	\| {pexp_desc = Pexp_ident {loc; txt}}

-                (* TODO: More elaborate warnings etc *)
+                (* TODO: Implement detailed warnings for invalid migration templates.
+                   Consider logging a warning with the location and details of the invalid template.
+                   Decide whether to fallback to a default behavior or propagate the error. *)

		(* TODO: More elaborate warnings etc *)
		(* Invalid config. *)

	(* TODO: More elaborate warnings etc *)
	(* Invalid config. *)
	handle_warning "Invalid configuration encountered during transformation.";

	(* TODO: More elaborate warnings etc *)
	(* Invalid config. *)
	handle_invalid_migration_config ~context:"Invalid migration template in deprecated function call";

-    (* TODO: Validate and error if expected shape mismatches *)
-    match reason with
-    | Some reason -> Some (reason, migration_template)
+    let validate_migration_template template =
+      match template.pexp_desc with
+      | Pexp_constant (Pconst_string (_, _)) -> Some template
+      | _ -> None
+    in
+    let validated_template = Option.bind migration_template validate_migration_template in
+    match reason with
+    | Some reason -> Some (reason, validated_template)

[WIP] Migrate command #7693

Are you sure you want to change the base?

[WIP] Migrate command #7693

Uh oh!

Conversation

zth commented Jul 21, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Instructions for adding more migrations to the stdlib

TODO

Uh oh!

pkg-pr-new bot commented Jul 22, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Reviewed Changes

Uh oh!

Copilot AI Jul 23, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jul 23, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jul 23, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jul 23, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jul 23, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

zth commented Jul 21, 2025 •

edited

Loading

pkg-pr-new bot commented Jul 22, 2025 •

edited

Loading